-
get-attachment-sizeGet Attachment Size -
get-media-usageGet Media Usage -
get-orphan-reportGet Unattached Files Report -
get-scanGet Scan -
get-site-storageGet Site Storage -
list-largest-attachmentsList Largest Attachments -
list-scansList Scans -
measure-sitesMeasure Sites -
start-orphan-reportStart Unattached Files Report -
start-scanStart Scan
Get Attachment Size
Measures one attachment now and returns the size of its file, of every generated variant and the total. Each variant comes with its size name, file, dimensions and size; a file shared by several sizes is counted once, and the pre-scaling original kept for large uploads is included. Also returns the variants total and the total stored by the background measurement (0 if it has not reached this attachment yet). Requires manage_options. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
attachment_id |
integer | Yes | Attachment ID. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Get Media Usage
Returns how much space a site’s media library takes, with breakdowns by MIME type group and by post status. The total covers every measured attachment, original file plus all generated variants, with how many attachments that covers, how many are still waiting to be measured and whether the background measurement has finished. MIME type groups (image, video, application and so on) are listed largest first. Attachments in every status count, including the trash, whose total is also given on its own because WordPress deletes it once the trash is emptied. Sizes are in bytes, each with a human-readable copy. Requires manage_options. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Get Unattached Files Report
Returns a site’s latest unattached files report, or the status of one in progress by its start-orphan-report job_id. Pass site_id, or job_id to follow a job (status queued, running, done or failed with error; the report comes with it once done). A report gives the uploads directory, when it ran, the driver, whether the listing finished within its time limit, totals for all files, files belonging to attachments and unattached files, unattached files grouped by top-level folder (year folders grouped by year), the largest unattached files with size and modified time, and how many files attachments refer to that are missing from disk, with examples. Paths are relative to the uploads directory. A site with no report returns status none. Requires install_plugins; main site only.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
site_id |
integer | No | The site whose latest report to return. | |
job_id |
string | No | A job from start-orphan-report. Use this or site_id. |
Get Scan
Returns one install scan: pass snapshot_id for a saved scan, or the job_id from start-scan to follow a background scan. For a job, status is queued, running, done or failed (with error); once done, the saved scan is returned with it. A scan has its directory (relative to the WordPress root), depth, driver, whether it finished within its time limit, its total, a size tree (each node with name, path, bytes and children, largest first, smaller directories grouped into one node with other true) and the files over 10 MB. max_depth trims the tree to fewer levels for a shorter answer. Requires install_plugins; main site only.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
snapshot_id |
integer | No | A saved scan, from list-scans. | |
job_id |
string | No | A job from start-scan. Use this or snapshot_id. |
|
max_depth |
integer | No | 0 |
Levels of the tree to return; 0 for all of them. |
Get Site Storage
Returns each site’s uploads directory and media library size from its last measurement, with network totals. Per site: the uploads directory on disk (for the main site, without the other sites’ uploads/sites folders), the measured media library and attachment count, attachments not yet measured, and when it was measured. uploads_complete is false where the measurement hit its time limit. Also returns how many sites have not been measured yet, the driver in use (du through the shell, or php) and whether a measurement pass is under way. Sorted by uploads (default), media or site_id. Sites are measured daily; measure-sites starts a pass now. Requires install_plugins; main site only.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
order_by |
string | No | "uploads" |
Sort order: uploads or media (largest first) or site_id. One of: uploads, media, site_id. |
limit |
integer | No | 200 |
Most sites to return. |
List Largest Attachments
Lists a site’s largest measured attachments, largest first by total size: the original file plus every generated variant. Each comes with its ID, title, file name, MIME type, post status (trash included), original, variants and total sizes and edit link. Optionally only one MIME type group, such as image, video or application. Attachments not yet measured by the background measurement are left out; get-media-usage says how many there are. Requires manage_options. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit |
integer | No | 20 |
How many to return. |
mime_group |
string | No | "" |
Optional MIME type group, such as image, video, audio or application. |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
List Scans
Lists saved install scans, newest first, and the background scan and report jobs that are queued, running or recently finished. The newest 20 scans are kept, each with its snapshot_id, when it ran, the directory (relative to the WordPress root), depth, driver, whether it finished within its time limit and its total size. Jobs are those queued, running or finished in the last day: install scans (type scan, with the snapshot_id once done) and unattached files reports (type orphans, with the site_id; read them with get-orphan-report). Use get-scan for a scan’s breakdown. Requires install_plugins; main site only.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit |
integer | No | 20 |
Most scans to return. |
Measure Sites
Starts measuring every site’s uploads directory and media library now in the background, instead of waiting for the daily pass. It runs on Action Scheduler where the main site has it, otherwise WP-Cron. A pass already under way carries on where it stopped unless restart is true, which starts again from the first site. Measuring a large network can take several minutes; poll get-site-storage, whose measuring flag stays true until the pass ends. Calling it again while a pass is scheduled schedules nothing more. Requires install_plugins; main site only.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
restart |
boolean | No | false |
Start again from the first site instead of resuming an unfinished pass. |
task_id |
integer | No | Optional. The lh-tasks task this call is working on. Pass with claim_token: the call is refused unless you hold that claim, and a successful call renews it. |
|
claim_token |
string | No | Optional. The claim_token from claim-next-task for task_id. Required when task_id is given. |
Start Unattached Files Report
Queues a background report of the files in one site’s uploads directory that no attachment accounts for, and returns the job. Every file on disk is compared with every file the site’s attachments, in any status, refer to (the attached file, each generated size, the pre-scaling original and modern image format copies). For the main site the other sites’ uploads/sites folders are skipped. It runs on Action Scheduler where available, otherwise WP-Cron, and returns at once; poll get-orphan-report with the job_id until its status is done. Only the latest report per site is kept, and nothing is ever deleted. Requires install_plugins; main site only.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
site_id |
integer | Yes | The site to report on. | |
task_id |
integer | No | Optional. The lh-tasks task this call is working on. Pass with claim_token: the call is refused unless you hold that claim, and a successful call renews it. |
|
claim_token |
string | No | Optional. The claim_token from claim-next-task for task_id. Required when task_id is given. |
Start Scan
Queues a scan of one directory of the install, run in the background through WP-Cron, and returns its job at once. The scan breaks the directory down by size to the given depth and, unless largest_files is false, lists the files over 10 MB. On a large install it can take several minutes. Poll get-scan with the job_id until its status is done, then read the snapshot it saved; failed jobs carry an error. Each call queues a new scan. Requires install_plugins; main site only.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
root |
string | Yes | Directory to scan. One of: install, wp-content, uploads, plugins, themes. |
|
depth |
integer | No | 2 |
Levels below the directory to break down. |
largest_files |
boolean | No | true |
Also list the files over 10 MB, which takes a second pass. |
task_id |
integer | No | Optional. The lh-tasks task this call is working on. Pass with claim_token: the call is refused unless you hold that claim, and a successful call renews it. |
|
claim_token |
string | No | Optional. The claim_token from claim-next-task for task_id. Required when task_id is given. |
